Folder Object

This section describes the purpose of a Folder object and its properties. Below you will find a general overview, followed by a detailed description of Folder Properties, as they appear in the Folder categories (tabs).

A Folder is one of three objects that are ActiveBatch containers. The other two containers are Plan objects and the root of the Job Scheduler. These are the three places that store ActiveBatch objects created by a Job author.

The Folder object allows you to organize your ActiveBatch objects in a meaningful way. The objects are located in the Object Navigation Pane. Folders are used to organize objects, and Plans are used to create workflows. As a best practice, organize your objects using Folders. Adding too many (non container) objects to the Scheduler's root (i.e. User Accounts, Jobs, Schedules, Queues, etc.) that are not in Plans and/or Folders may create organizational difficulties.

To create a Folder, right-click on the desired container (Scheduler root, existing Folder or Plan) in the Object Navigation pane, select New, then select Folder. The label of the new Folder must be unique to the container where it is being added. When you’ve completed the Folder property settings, you must click the Save or the Save and Close button to save the Folder. Click the X on the tab of the New Folder if you wish to cancel the creation of the Folder. When you save the Folder it will instantly appear in the Object Navigation pane (if auto refresh is enabled) and will be ready for you to add objects to it. To modify an existing Folder, right-click on the Folder in the Object Navigation pane, then select Properties.

A Folder is similar to a Plan in that it can contain all of the other ActiveBatch objects within it (including nested Folders). Unlike Plans, Folders cannot be triggered. However, Folders and Plans do support some similar functionality (e.g. variables, policies, etc.).

Below are some key points about Folders:

• Think of a Folder the way you would an operating system's file system. When using an operating system's file system, you would likely create Folders, nested Folders, etc. to organize your files, so they can be easily found. The same is true for ActiveBatch Folders. Placing objects in a Folder provides a form of isolation. For example, if you place Jobs, Plans, Queues and User Account objects within a Folder, you eliminate its visibility outside the Folder. Users traversing the Object Navigation tree need List/Connect rights to see the contents of the Folder and/or to optionally connect to it using the Virtual Root Virtual root is an optional feature that allows you to connect to a Job Scheduler via a Folder (best practice) or Plan object, as opposed to connecting to the root of the Job Scheduler. When connected to a Virtual Root, the user's scope is limited. They will only see and have access to objects and instances that are child objects within the connection point. This feature can be used for security purposes, or simply to de-clutter a user's view, if they don't need to see or have access to containers that are not their concern.   facility.

• Folders are not triggerable. Since Folders cannot be triggered, there are no Folder instances.

• Folders cannot be enabled or disabled (although there is a right-click menu option allowing you to disable child objects of the selected Folder).

• You can set (define) variables on a Folder, and the child objects that reference variables will be able to access them (they will be within the child objects' scope).

• You can set security on a Folder so that child objects can inherit security from the Folder.

• You can set default policies A default policy allows you to preset a new object's properties to override factory default property values, and/or preset properties that are blank by default. See Default Policy for more details.  on a Folder.

• You can set audit policies An audit policy provides a way for a user to add additional audit information when working with ActiveBatch objects and/or instances. For example, an audit policy can be created that prompts an ActiveBatch user to enter a reason why they are modifying an object, or disabling an object, or manually triggering a Job or Plan. The reason entered is stored in the audit trail of the object or instance. For more details see Audit Policy. on a Folder.

• You can connect to a Folder using ActiveBatch's Virtual Root feature, mentioned above.

Note: To learn about how to best set up objects in the Object Navigation pane, see this topic: Organizing ActiveBatch Objects

Folder Properties

General

 

The image below depicts the General category of an existing Folder.

 

 

General Properties

 

Name: This mandatory property represents the name of the object. The name is limited to 128 characters. The object’s name should be unique to avoid confusion. We recommend that it also be somewhat descriptive so it’s easy to find. The name is used (by default) to identify the object in the Object Navigation pane and other places in the UI. This can be changed to the label, if desired. See "Display Mode" in the General Settings

 

Label: Every object must be uniquely labeled within the scope of the namespace. The label is limited to sixty-four (64) characters. The label is typically the same value as the name (it is auto-filled to match the name you enter); however, uniqueness is always enforced for an object’s label. The label is recorded in the ActiveBatch namespace. The characters that may be used for the label property are restricted to alphanumeric (A-Z, a-z, 0-9), space, period (.), dash (-) and underscore (_). The label itself must begin with an alphabetic character. The label is typically used when scripting. All searches are case-insensitive. ActiveBatch does allow you to search for objects using either the label or the name properties.

 

ID: This is a unique read-only number that can be used to retrieve the object. Is it assigned by the system when a new object is saved.

 

Full Path: This read-only property provides the full namespace specification of the object. It consists of the container(s) the object has been placed in, with the object’s label appended to the end. For example, the fullpath: /IT Jobs/Nightly Run/<object label>, is such that IT Jobs is a root-level Folder, Nightly Run is a Plan, followed by the label of the object you are creating.

 

Description: This free form property is provided so you can document and describe the object to others. The description is limited to 512 characters. Clicking on the pencil icon will pull up a mini text editor where you can more easily enter your description.

 

Documentation: This optional field is used to denote a reference to the Folder in an operator’s runbook or other documentation concerning the running of the nested objects (to a maximum of 80 characters). Clicking on the pencil icon will cause a mini text editor to appear.

 

User Defined: This optional field can be set by the Folder’s author as free-form text (to a maximum of 128 characters). If you set this field as a URL (for example, a hot link to runbook information for this Plan) you can click the button on the right and launch your web browser with this field as a URL.

 

Category: This optional field is used to categorize the Folder (to a maximum of 64 characters).

 

Group: This field is not used and is obsolete (it is maintained for backward compatibility purposes only). Folders are now used to associate related objects. The maximum group name length is 64 characters.

 

Read Only: This checkbox, when enabled, means the Folder's properties cannot be changed.  You must have “Modify” access permission to the Folder object to set this feature.  To clear the read-only attribute, uncheck the box.

Variables

 

Variables can be created on the Folder-level.  Objects that use (reference variables) that have the Folder object in their full path will be able to access the variables. For example, if FolderA has a variable Var1 defined on it, a Job with the following full path will able to access it. /FolderA/FolderB/FolderC/PlanA/Job1.

 

 

ActiveBatch variables represent data that can be passed to Jobs, Plans, programs or used anywhere variable substitution may be used within ActiveBatch. 

Analytics

 

This category allows you to view the audits associated with the Folder object.

 

 

The first audit indicates when the Folder was created. Changes made to the Folder are also audited.

 

The Audits panel includes controls that allow you to filter the audits based on start and end dates. You can also limit the audits retrieved to a maximum number. The refresh button allows you to retrieve any audits that were generated after this dialog was initially displayed.

 

Each audit is contained in a single line in date and time sequence. Audits are read-only and cannot be modified. An icon appears at the beginning of each audit to help visually signal the severity of the audit. If an audit policy An audit policy provides a way for a user to add additional audit information when working with ActiveBatch objects and/or instances. For example, an audit policy can be created that prompts an ActiveBatch user to enter a reason why they are modifying an object, or disabling an object, or manually triggering a Job or Plan. The reason entered is stored in the audit trail of the object or instance. For more details see Audit Policy. has been established, you will see an additional comment icon to the right of the severity icon. If you mouse over the comment icon, the system will display the audit information as a tooltip.

 

Opening an audit item (by double-clicking on the item), depending on the nature of the audit, will sometimes reveal additional information concerning the audit. 

 

The Copy to Clipboard button copies the contents of the retrieved audits into a copy buffer that you can later paste into a document or other program.

 

The Print button allows you to print the retrieved audits.

 

The Revision History button allows you to select one or more audits concerning changes made to an object and perform a difference operation between the selected revised objects.

Security

This tab is where object security is configured. Security in ActiveBatch mirrors how security is granted using Windows security. That is, permissions applicable to the object (Read, Write, Modify, Delete, etc.) are Allowed or Denied for the Active Directory users and/or groups assigned to the object.

 

 

Note: The Owner field has been omitted in the above figure intentionally.

 

To add, edit or remove security access permissions requires the user to have “Change Permissions” access to the object.

 

The table below lists all security access permissions, using Windows conventions, that you will see on a Folder's security property sheet.

    

Access	Description
Read	Account is allowed to view any properties/variables of the Folder (Note: Read implies both Read Properties and Read Variables).
Read Properties	Account is allowed to read the properties of the Folder.
Read Variables	Account is allowed to read the variables of the Folder.
Write	Account is allowed to write to the Folder.
Modify	Account is allowed to read/write any properties of the Folder (Read + Write).
Delete	Account is allowed to delete the Folder.
Take Ownership	Account is allowed to take ownership of the Folder.
Use	Account is allowed to use the Folder. Applicable on Push Down or Inheritance of Security only.
Manage	Account is allowed to perform operations (Enable/Disable or Hold/Release). Applicable on Push Down or Inheritance of Security only.
List/Connect	Account is allowed to list objects in the Folder and/or connect to the Folder as a virtual root.
Instance Control	Account is allowed to manage instances (e.g. restart, cancel, force run, etc.) Applicable on Push Down or Inheritance of Security only.
Create Objects	Account is allowed to manipulate objects contained in the Folder. This includes add, delete and move. The account must also have the necessary corresponding permissions on the underlying object itself.
Change Permissions	Account is allowed to change permissions (set security) on the Folder.
Trigger	Account is allowed to perform the trigger operation. Applicable on Push Down or Inheritance of Security only.
Trigger and Change Queue	Account is allowed to trigger a Job and specify a Queue where it should run. Applicable on Push Down or Inheritance of Security only.
Trigger and Change Parameters	Account is allowed to trigger an object and specify new or existing ActiveBatch variable(s) and/or parameters that override any specified at the Job/Plan level. Applicable on Push Down or Inheritance of Security only.
Trigger and Change Credentials	Account is allowed to trigger a Plan or Job and specify new security credentials for the Plan’s variables that require security credentials. Applicable on Push Down or Inheritance of Security only.
Full Control	Account may issue all of the operations mentioned above.

 

In the above table, there are several references that state: Applicable on Push Down or Inheritance of Security only. This means the security permission is not applicable to the Folder object itself. For example, you can't trigger a Folder and therefore there are no instances to control. The permissions are there because child objects in the Folder may obtain their security from the Folder (which is an option, not a requirement), and if they do, all permissions related to all object types must be present on the Folder's security property sheet. The reference to "Push Down" and "Inheritance of Security" are the two ways that child objects can obtain their security from the Folder. See below for more details.

 

Push down - Push down provides you with a way to propagate the Folder's permissions to the objects nested within the Folder. This means the Folder's existing child objects (and nested child objects) will have their security removed, then replaced to match the Folder's security groups and/or user names and their associated permissions. The "Replace Permission entries on all child object with entries shown here" checkbox (as depicted in the above image) enables the push down action. Note! You will only see this property if the Folder's "Inherit Security from Parent Object" property is not checked.

 

When you check the "Replace permission entries..." checkbox, then save the Folder, the push down action will take place. Therefore, the "Replace permission entries..." checkbox is an action item, not a static property setting.  Since it is an action item, the next time you edit the Folder's security property sheet, the property will be unchecked, by design. You can use this feature as often as you would like, since updating Folder security does not automatically update child object security, unless child object security is inheriting security from its parent object.

 

Inheritance of Security - Child objects inherit security from its parent container when the child object's "Inherit Security from Parent Object" property is checked. This property is on the security property sheet of all objects, including Plan and Folder objects (they can inherit their security from their parent container). In addition, when Inherit Security from Parent Object is checked on the Folder, you will see another property named "Enable inherit security on all child objects". This property allows you to push down "inherit security" to all child objects (and nested child objects) within the Folder. This process removes existing child object security and replaces it with inherit security by enabling (checking) the "Inherit Security from Parent Object" property for each child object. When you check the "Enable inherit security on all child objects." checkbox, then save the Folder, the push down action occurs during the save. Therefore, the "Enable inherit security on all child objects" checkbox is an action item, not a static property setting. Since it is an action item, the next time you edit the Folder's security property sheet, the property will be unchecked, by design. You can use this feature as often as you like.

 

Note: Pushing down security (users/groups) is an option that allows you to quickly update child object security within a container. It is more commonly used when a customer decides existing objects created using factory default security Factory default security works as follows - When any new object type is created, the security assigned to the object includes two Active Directory groups - Authenticated Users and Administrators. Administrators are granted Full Control access to all objects, and Authenticated Users are granted a more limited set of permissions. does not match their security requirements. It could be quite tedious to update each object with new security, hence the ability to push down security. It was also used when a container's security changed. The only way to propagate the change was by using the push down feature. With the introduction of inherit security, you can now change container security which will dynamically update child object security, as long as the child objects have the "Inherit Security from Parent Object" checkbox checked. In order to allow customers to easily switch to inherit security (at the time it was introduced), the push down inherit security option was made available, again, to speed up the process of making a sweeping security change.

Note: The easiest approach to managing security would be to determine what container(s) you need to set security on, add the desired users and/or groups and grant the appropriate permissions, then create a default policy A default policy allows you to preset a new object's properties to override factory default property values, and/or preset properties that are blank by default. See Default Policy for more details.  for each (new) object type that will be added to the container - with the object's "Inherit Security from Parent Object" checkbox enabled (it is not enabled by default). If security changes on the parent container, it is automatically reflected in the child objects.

 

 

The owner of a Folder is the user who first creates the Folder. The owner of a Folder is implicitly granted Full Control access permission, and this cannot be changed. To change ownership, click the Take Ownership button and confirm the resulting dialog. You can also take ownership by right-clicking on the Folder in the Object Navigation pane, then selecting Advanced > Take Ownership. If ownership is changed, the new owner is automatically granted Full Control access to the object, and this cannot be changed. Note: You must be granted Take Ownership permission to take ownership of an object.

 

The Deny permission is generally used for users who have been granted access based on a group membership, but there is a need to override this for a user. Deny takes precedence over Allow.

 

When the "Inherit Security from Parent Object" is checked, you cannot add, remove or modify security permissions for the existing users/groups. Therefore the discussion below assumes this property is not checked.

 

To add new access permissions, click the Add button and follow the dialog as discussed below under the Add Security Dialog heading. To remove an existing account name, select the listed account and click the Remove button. To change existing access permissions, select the account and then select a new Permission Type (either Grant or Deny access) and a new Permission (one of the access permissions listed in the above table).

 

Add Security Dialog

 

 

The dialog is similar to that of other Windows objects, and leverages Active Directory services. The Locations button allows you to select either the Job Scheduler machine or any applicable domain. Clicking the Advanced button allows you to search for specific users and/or groups. Alternatively, you may enter object names (a user or group) in the large edit box. Clicking the Check Names button allows you to validate the accounts. Click the OK button to add the selected Account to the object’s security list.